Skip to content

DOC-7104: Migrate content/operate/rs/7.4/references/ (incl. rest-api) to render hooks - #4094

Merged
andy-stark-redis merged 4 commits into
mainfrom
DOC-7104-7.4-references
Sep 24, 2026
Merged

andy-stark-redis merged 4 commits into
mainfrom
DOC-7104-7.4-references

Conversation

@andy-stark-redis

@andy-stark-redis andy-stark-redis commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Unit 10 of 15 in the DOC-7104 shortcode-to-render-hook migration: converts every file under content/operate/rs/7.4/references/ (including rest-api/) from {{< relref >}} and {{< note >}}/{{< warning >}} shortcodes to plain Markdown links and > [!NOTE]/> [!WARNING] blockquotes resolved by the DOC-6909 render hooks (layouts/_default/_markup/render-link.html and render-blockquote.html).

The rest-api/ subtree (169 of the 246 files) is explicitly in scope per the ticket: this frozen 7.4 snapshot was generated once and never regenerated, so a one-time conversion is safe and permanent.

  • Files changed: 167 of 246 markdown files under content/operate/rs/7.4/references/
  • Real counts (re-measured by grep): 1029 relref shortcodes across 165 files; 20 callouts (16 note, 4 warning, 0 tip/info/alert) across 16 files; 14 files carried both.
  • Hand-fixed gotcha: cli-utilities/rladmin/_index.md had a {{<note>}} indented inside a numbered list item, with only the header line indented by the converter and the continuation/closing lines left flush left, plus a stray whitespace-only > artifact line. Re-indented all blockquote lines to match the list item and dropped the stray line. Verified via rendered HTML (before vs. after) that the <li> nesting is unchanged.
  • Pre-existing defect flagged, not fixed: cli-utilities/redis-cli/_index.md line 153 has a markdown link with a relref shortcode but no closing ) — confirmed via git show HEAD that this was already broken before this migration. Left unconverted per "a missed rewrite is fine, a wrong one is not."
  • No relref-missing-slash instances found.

Verification

  • Full-site Hugo builds before/after (non-minified — hugo --minify currently fails site-wide on an unrelated pre-existing esbuild error on /commands/cf.reserve, confirmed pre-existing in unit 8).
  • build/diff_rendered_hrefs.py (patched version from DOC-7104-diff-hrefs-fix, used for verification only and not included in this diff) scoped to operate/rs/7.4/references: 244/244 pages compared, 0 href-set changes.
  • Confirmed build/diff_rendered_hrefs.py carries no changes in this PR's diff.

Test plan

  • CI build passes
  • Spot-check a few converted pages (especially cli-utilities/rladmin/_index.md and the rest-api/ callout pages) render correctly
  • Confirm the flagged pre-existing broken link in cli-utilities/redis-cli/_index.md is tracked separately if it needs a fix

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only mechanical conversion of links and callouts in a static 7.4 snapshot; no runtime or security impact.

Overview
Migrates the frozen Redis Enterprise 7.4 references tree (CLI utilities, compatibility tables, metrics, REST API docs, and related pages) off Hugo shortcodes so render hooks can resolve links and callouts.

Internal links: {{< relref "..." >}} is replaced with plain Markdown targets under /content/... (including _index.md, .md, and hash anchors). The change is broad—crdb-cli, rladmin, redis-cli, command-compatibility matrices, and cross-links to RS/RC/develop/commands content all follow the same pattern.

Callouts: {{< note >}} / {{< warning >}} become > [!NOTE] and > [!WARNING] blockquotes (e.g. internal CLI utilities warning, rladmin shell note, RESP3 notes, REST API warnings).

No product behavior or API semantics change; this is documentation markup only, aligned with the DOC-7104 shortcode-to-render-hook migration for this directory.

Reviewed by Cursor Bugbot for commit aaf1b78. Bugbot is set up for automated code reviews on this repo. Configure here.

… to render hooks

Unit 10 of 15: converts the frozen 7.4 references tree (246 files, 167
carrying relref/callout shortcodes) from {{< relref >}} and
{{< note >}}/{{< warning >}} shortcodes to plain markdown links and
> [!NOTE]/> [!WARNING] blockquotes resolved by the DOC-6909 render hooks.
The rest-api/ subtree (169 of the 246 files) is explicitly in scope per
the ticket: it was generated once when 7.4 was frozen and never
regenerated since, so a one-time conversion is safe and permanent.

Real counts (re-measured by grep, not taken from the ticket estimate):
1029 relref shortcodes across 165 files, 20 callouts (16 note, 4 warning,
0 tip/info/alert) across 16 files; 14 files carried both. Post-conversion
grep confirms 0 remaining shortcode-form relref/callout instances except
one pre-existing defect (see below), and 167/246 files touched overall.

One gotcha instance found and hand-fixed: cli-utilities/rladmin/_index.md
had a {{<note>}} indented inside a numbered list item, with only the
header line indented and the continuation/closing lines flush left (the
known converter limitation), plus a stray whitespace-only `>` artifact
line left by the closing tag's indentation. Fixed by re-indenting all
blockquote lines to match the list item and dropping the stray line;
verified via rendered HTML that the <li> nesting is unchanged before/after
(alert div closes inside the same <li>, immediately before </ol>, in both
builds).

Flagging, not fixing, a pre-existing defect: cli-utilities/redis-cli/_index.md
line 153 has `[Redis commands reference]({{< relref "/commands/" >}}` with
no closing `)` -- the link was already malformed before this migration
(confirmed via `git show HEAD` on the original), so the relref-to-plain
regex correctly left it unconverted rather than guessing. Left as-is per
"a missed rewrite is fine, a wrong one is not" and the AGENTS.md rule to
flag technical defects rather than silently fix them.

No relref-missing-slash instances found in this unit.

Verification: full-site hugo builds before/after (non-minified -- see
below), diffed with the DOC-7104-diff-hrefs-fix build/diff_rendered_hrefs.py
scoped to operate/rs/7.4/references: 244/244 pages compared, 0 href-set
changes. The verification-only patched diff script was staged from
origin/DOC-7104-diff-hrefs-fix, then unstaged and reverted before this
commit; build/diff_rendered_hrefs.py carries no changes here.

Build note: `hugo --minify` currently fails site-wide on this checkout with
a pre-existing esbuild syntax error while minifying a script on
/commands/cf.reserve, unrelated to this unit's path (confirmed pre-existing
in unit 8). Verification builds ran without --minify; both before and after
used identical flags, and rendered hrefs are unaffected by minification, so
the comparison is still valid.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

DOC-7104

@github-actions

Copy link
Copy Markdown
Contributor

Staging links:
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/purge-instance/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/remove-instance/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/update/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/crdb-cli/task/status/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/redis-cli/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/bind/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/cluster/certificate/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/cluster/config/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/failover/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/migrate/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/addr/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/enslave/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/external-addr/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/maintenance-mode/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/recovery-path/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/remove/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/node/snapshot/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/placement/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/recover/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/tune/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/upgrade/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/cli-utilities/rladmin/verify/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/client_references/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/clustering-redis/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/compatibility/
https://redis.io/docs/staging/DOC-7104-7.4-references/operate/rs/7.4/references/compatibility/commands/

…x.md

The unit-10 subagent correctly left this pre-existing malformed relref
(missing its closing paren) unconverted rather than guessing at a fix,
per the migration script's by-design behavior. Fixing it here so this
unit doesn't leave one relref shortcode behind in an otherwise fully
converted file, matching the pattern already applied in units 1 and 2.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

@dwdougherty dwdougherty left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few things to check...

---

The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands]({{< relref "/commands" >}}) directly from the command-line terminal or with [interactive mode](#interactive-mode).
The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bad link. Suggestion is questionable.

Suggested change
The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode).
The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/content/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode).

- [Redis CLI documentation]({{< relref "/develop/tools/cli" >}})
- [Redis commands reference]({{< relref "/commands/" >}}
- [Redis CLI documentation](/content/develop/tools/cli.md)
- [Redis commands reference](/commands/)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content/commands ?

---

The following tables show which Redis Open Source [connection management commands]({{< relref "/commands" >}}?group=connection) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.
The following tables show which Redis Open Source [connection management commands](/commands?group=connection) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content... ?

---

The following table shows which Redis Open Source [pub/sub commands]({{< relref "/commands" >}}?group=pubsub) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.
The following table shows which Redis Open Source [pub/sub commands](/commands?group=pubsub) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content... ?

---

The following table shows which Redis Open Source [scripting and function commands]({{< relref "/commands" >}}?group=scripting) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.
The following table shows which Redis Open Source [scripting and function commands](/commands?group=scripting) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content ... ?

---

The following tables show which Redis Open Source [server management commands]({{< relref "/commands" >}}?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.
The following tables show which Redis Open Source [server management commands](/commands?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content ... ?

---

The following table shows which Redis Open Source [transaction commands]({{< relref "/commands" >}}?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.
The following table shows which Redis Open Source [transaction commands](/commands?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/content ... ?

| Method | Path | Description |
|--------|------|-------------|
| [PUT]({{< relref "./backup_reset_status#put-bdbs-actions-backup-reset-status" >}}) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status |
| [PUT](./backup_reset_status#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bunch of bad/questionable links on this whole page.

Comment on lines +25 to +33
| [GET](./all#get-all-debuginfo) | `/v1/debuginfo/all` | Gets debug info for all nodes |
| [GET](./all/bdb#get-all-debuginfo-bdb) | `/v1/debuginfo/all/bdb/{bdb_uid}` | Gets debug info for a database from all nodes |

## Get debug info for the current node

| Method | Path | Description |
|--------|------|-------------|
| [GET]({{< relref "./node#get-debuginfo-node" >}}) | `/v1/debuginfo/node` | Gets debug info for the current node |
| [GET]({{< relref "./node/bdb#get-debuginfo-node-bdb" >}}) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node |
| [GET](./node#get-debuginfo-node) | `/v1/debuginfo/node` | Gets debug info for the current node |
| [GET](./node/bdb#get-debuginfo-node-bdb) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Questionable links here.

…(same fix as #4093 review)

Same defect pattern found and fixed on PR #4093 (7.22/references) after
human review: 7 bare /commands?group=<x> links in compatibility/commands/
missing the /content/ prefix, and 10 source-relative relrefs in
rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a
directory/file with no extension (works via Hugo's render-link.html
GetPage resolution, confirmed byte-identical rendered href before/after,
but not a working link when the same markdown renders in GitHub's PR
view or VS Code). This version snapshot is a near-identical copy of
7.22's rest-api tree, so the same instances recur in the same two files.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@andy-stark-redis

Copy link
Copy Markdown
Contributor Author

Proactively applied the identical fix that #4093's review caught (same pattern: bare /commands?group=x links missing the /content/ prefix, and 7 source-relative refs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the exact same instances recurred in the same two files. Verified 0 href diffs before/after.

andy-stark-redis added a commit that referenced this pull request Sep 24, 2026
…o slash

The original regex required `/` or end-of-string right after the mount
name, so a link like `/commands?group=cluster` (no trailing slash before
the query) silently passed through unchecked -- this tool's own blind
spot, found the hard way: human review caught it by hand on DOC-7104
PR #4093, and the identical instances recurred in #4094/#4096/#4098
before this fix existed to catch them.

Also reconsiders the `/commands` special case: it has no backing
_index.md on disk, so _find_content_file always reports it unresolvable,
but Hugo auto-generates a section page for the directory and GetPage
finds it anyway (confirmed by building both /commands?group=x and
/content/commands?group=x and comparing rendered hrefs -- identical).
Review wanted the canonical form applied there too, so it's now
hardcoded as FIXABLE instead of silently skipped.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis added a commit that referenced this pull request Sep 24, 2026
…w pattern as #4094)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@andy-stark-redis

Copy link
Copy Markdown
Contributor Author

Fixed. Also swept for and fixed the same defect class elsewhere (7.22/7.8/8.0 references, plus the live tree via #4103).

andy-stark-redis added a commit that referenced this pull request Sep 24, 2026
…r hooks

Converts relref link shortcodes and note/tip/warning/alert callout
shortcodes to render-hook equivalents across content/operate/rs/7.4/,
excluding references/ (done separately in #4094) -- 145 of 162 files,
936 relref links and 155 callouts.

Found and fixed the recurring indented-callout bug (27 files, ~30
blocks) and the recurring HGETALL missing-paren relref in
databases/connect/troubleshooting-guide.md (3rd version to carry it:
live tree, 7.22, now 7.4). Flagged, not fixed: 6 pre-existing broken
relref targets in new-features-redis-enterprise.md (draft: true, never
renders) -- same 6 targets that recur in every version.

Review (round 2) caught three more issues, all fixed -- same as #4095:
- Bare /commands links in _index.md and
  security/access-control/redis-acl-overview.md, missing the /content/
  prefix (confirmed identical rendered href either way).
- new-features-redis-enterprise.md's 6 dead links: applied the same
  /content/ prefix for consistency. Cosmetic only -- none of the 6
  targets exist regardless of prefix.
- databases/import-export/flush.md: the port-configurations link's
  anchor was a stray old absolute URL concatenated into the fragment,
  predating this migration. Replaced with the real heading slug.

Verified via build/diff_rendered_hrefs.py: after filtering the known
CSS-asset-fingerprint noise from comparing builds in two different
worktree environments, the only real content change is the corrected
flush.md anchor -- everything else confirmed 0 diff.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis added a commit that referenced this pull request Sep 24, 2026
migrate_shortcode_links.py's linkify stage correctly canonicalizes almost
every converted link to /content/<path>.md[#anchor], but a link that
gets a manual post-hoc text fix after the pipeline already ran (e.g.
inserting a separator slash a relref-plus-literal-suffix concatenation
was missing) never gets a second pass through linkify. The result is a
bare /operate/... path that resolves to the exact same rendered href as
the canonical form, so build/diff_rendered_hrefs.py -- this migration's
usual verification -- is blind to it by construction.

Found on PR #4086 (release-notes/ unit): human review manually flagged 8
malformed links; a corpus-wide grep for the same shape found 21 across 9
files (13 more than manual review caught), plus 8 more that turned out
to be genuinely pre-existing dead links in the identical shape, invisible
to any prior check since Hugo's relref shortcode only ever validated its
own target, never text concatenated onto it afterward.

check_uncanonicalized_links.py reuses migrate_shortcode_links.py's own
resolver (_find_content_file) so a --fix run applies the exact same
rewrite the pipeline would have. Three outcomes: FIXABLE (resolves,
--fix rewrites it), MOUNT_ONLY (resolves only through a Hugo module
mount -- never auto-fixed, same rationale _find_content_file already
documents for not following mounts on a rewrite), DEAD (doesn't resolve
at all -- reported only, never guessed).

A second commit fixed the tool's own blind spot, found immediately on
its first real use: the original MOUNT_PREFIX_RX required a `/` or
end-of-string right after the mount name, so a bare `?query`/`#fragment`
with no slash before it (e.g. /commands?group=x) silently passed through
unchecked -- exactly the shape human review caught by hand across
DOC-7104 PR #4093/#4094/#4096/#4098. Also reconsidered the `/commands`
special case: it has no backing _index.md on disk so the filesystem
resolver always calls it unresolvable, but Hugo auto-generates a section
page for the directory and GetPage finds it anyway (confirmed by
building both /commands?group=x and /content/commands?group=x and
diffing rendered hrefs -- identical). Now hardcoded as FIXABLE instead
of silently skipped.

Verified against the pre-fix state of PR #4086: reproduces the exact
21 FIXABLE / 8 DEAD split. A full-corpus scan of content/ elsewhere
comes back to 3 unrelated hits, confirming it isn't noisy. 8 unit tests
cover both commits' behavior.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@andy-stark-redis
andy-stark-redis merged commit 836665f into main Sep 24, 2026
99 checks passed
@andy-stark-redis
andy-stark-redis deleted the DOC-7104-7.4-references branch September 24, 2026 13:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants